Configuring Connection Failover for the JDBC Client

Connection failover allows an application to connect to an alternate, or backup, database server if the primary database is unavailable, for example, because of a hardware failure or traffic overload. Connection failover ensures that the data on which your critical JDBC applications depend is always available.

You can customize the JDBC Client for connection failover by configuring a list of alternate database servers that are tried if the primary server is not accepting connections. Connection attempts continue until a connection is successfully established or until all of the alternate database servers have been tried the specified number of times.

Specifying Primary and Alternate Servers

Connection information for primary and alternate servers can be specified using either a connection URL through the JDBC Driver Manager or a JDBC data source. For example, the following connection URL for the JDBC Client specifies connection information for the primary and alternate servers using a connection URL:

jdbc:sequelink://server1:19996;serverDataSource=SDSN1;User=test;
Password=secret;AlternateServers=(server2:19996;serverDataSource=SDSN2,
server3:19996;serverDataSource=SDSN3) 

In this example:

...server1:19996;serverDataSource=SDSN1... 

is the part of the connection URL that specifies connection information for the primary server. Alternate servers are specified using the AlternateServers property. For example:

...;AlternateServers=(server2:19996;serverDataSource=SDSN2,
server3:19996;serverDataSource=SDSN3) 

Similarly, the same connection information for the primary and alternate servers specified using a JDBC data source would look like this:

SequeLinkDataSource mds = new SequeLinkDataSource(); 
mds.setDescription("My SequeLinkDataSource"); 
mds.setServerName("server1"); 
mds.setPortNumber(19996); 
mds.setServerDataSource("SDSN1"); 
mds.setUser("test"); 
mds.setPassword("secret"); 
mds.setAlternateServers(server2:19996;serverDataSource=SDSN2, 
server3:19996;ServerDataSource=SDSN3)  

In this example, connection information for the primary server is specified using the ServerName, PortNumber, and serverDataSource properties. Connection information for the alternate servers is specified using the AlternateServers property.

Using the AlternateServers Property

Connection information for alternate servers is specified using the AlternateServers property with either a connection URL or a JDBC data source. The value of the AlternateServers property is a string that has the format:

(servername1:port1[;serverDataSource=SDSN1;][,servername2: 
port2[;serverDataSource=SDSN2]...) 

where:

servername1 is the IP address or server name of the first alternate database server, servername2 is the IP address or server name of the second alternate database server, and so on. The IP address or server name is required for each alternate server entry.

port1 is the port number on which the first alternate database server is listening, port2 is the port number on which the second alternate database server is listening, and so on. The port number is required for each alternate server entry.

serverDataSource=SDSN2 is the server data source name for the first alternate server, serverDataSource=SDSN3 is the server data source name for the second alternate server, and so on. Currently, the only optional property that can be set for the alternate server is serverDataSource. For example:

jdbc:sequelink://server1:19996;serverDataSource=SDSN1;User=test;Password=
secret;AlternateServers=(server2:19996;serverDataSource=SDSN2) 

Specifying Connection Retry

Connection retry allows the JDBC Client to retry connections to the primary database server, and if specified, alternate servers until a successful connection is established. You use the ConnectionRetryCount and ConnectionRetryDelay properties to enable and control how connection retry works. For example:

jdbc:sequelink://server1:19996;serverDataSource=SDSN1;User=test;Password=
secret;AlternateServers=(server2:19996;serverDataSource=SDSN2,
server3:19996;serverDataSource=SDSN3);ConnectionRetryCount=2;
ConnectionRetryDelay=5 

In this example, if a successful connection is not established on the JDBC Client's first pass through the list of database servers (primary and alternate), the JDBC Client retries the list of servers in the same sequence twice (ConnectionRetryCount=2). Because the connection retry delay has been set to five seconds (ConnectionRetryDelay=5), the JDBC Client waits five seconds between retry passes.

Specifying Load Balancing

Client load balancing helps distribute new connections in your environment so that no one server is overwhelmed with connection requests. When client load balancing is enabled, the order in which primary and alternate database servers are tried is random.

When Connection Retry is also enabled, the JDBC Client tries to connect to the primary SequeLink server and alternate SequeLink servers in a random order until a successful connection is established. If the connection attempt fails, the driver again randomly selects from the list of servers until all SequeLink servers in the list have been tried or a connection is successfully established.

Connection Failover Properties

Table 10-1 summarizes the connection properties that control how connection failover works with the JDBC Client. Refer to the SequeLink Developer's Reference for details about configuring each property.

Table 10-1. Summary: Connection Failover Properties for the JDBC Client 

Property	Characteristic
AlternateServers	List of alternate database servers. An IP address or server name and a port number are required for each server. The serverDataSource connection property is optional.
ConnectionRetryCount	Number of times the driver retries the primary database server, and if specified, alternate servers until a successful connection is established. The initial default is 0.
ConnectionRetryDelay	Wait interval, in seconds, between connection retry attempts when the ConnectionRetryCount property is set to a positive integer. The initial default is 3.
LoadBalancing	Sets whether the driver will use client load balancing in its attempts to connect to the list of database servers (primary and alternate). If client load balancing is enabled, the driver uses a random pattern instead of a sequential pattern in its attempts to connect. The initial default is false (client load balancing is not used).

Refer to the SequeLink Developer's Reference for overviews of connection failover and client load balancing.